[0.9.0] Season seats: set_aside_season_block, retrieve_season_block, release_season_block, inventoryMode - #14

Season seats for the seatlayer gem, part of the 0.9.0 release. One release, 0.9.0, carries season 2a (#13) and this PR (decided 10 Nov).

• Versions: old 0.8.0 (published) → new 0.9.0 (with season-2a, Season 2a server operations (part A) #13). Nothing is published yet: RubyGems stops at 0.8.0 (checked 10 Nov).
• 0.8.0 has the 48 season operations from 0.7.0/0.8.0. It has none of the season-2a calls and none of these.
• The branch is cut from season-2a-server so it builds on the season-2a methods. Its name still says 0.10.0, from before the decision: renaming a head branch would close the PR.
• No version bump, tag or publish is in this PR. SeatLayer::VERSION is untouched.

What it adds

Built to docs/season-block-2026-11-08/contract.md in the app repo (§2, §5, §6, and §8 "Amendments, 9 Nov"). Method names are the operationIds, snake_cased.

• Methods:

  • seasons.set_aside_season_block(season_key, expected_revision:, keep_for_single_tickets: nil, idempotency_key: nil);
  • seasons.retrieve_season_block(season_key);
  • seasons.release_season_block(season_key, expected_revision:, scope:, event_keys: nil, at: nil, reason: nil, idempotency_key: nil).

  Both writes use the :header_replay retry policy, so an Idempotency-Key is generated when none is given, as on refund_season_performance. Each write answers "job" and "block"; follow the job with retrieve_season_bulk_job.

• inventory_mode: ("block" | "per_hold") on create_season and update_season, sent as "inventoryMode" only when given. "block" opts the season into season seats; the default stays per_hold. Every Season answer carries "inventoryMode".

• Webhook names: Webhooks::EVENT_NAMES adds season.block.ready and season.block.released, in the API's order (56 → 58). create and update check names against this list and raise ArgumentError for any other. Without this, 0.9.0 would refuse the two new names; 0.8.0 refuses them.

• The 202 while a date leaves every season seat (create_season_amendment cancel, mark_season_performance_past): SeatLayer::Seasons.date_leave_pending?(answer). The return values are unchanged.

• Errors: no new classes or constants. The new codes come through SeatLayer::APIError and its subclasses with code (§8 item 4). The CHANGELOG lists them, now including every code the 3 calls and inventory_mode: can send (SEASON_BLOCK_API_BUSINESS_ERRORS in the app repo).

• Docs: a "Season seats" section at the end of the README's "Fixed Renewable Seasons": opt in with inventory_mode:, set the seats aside, follow the job, read the block, release to single sale (now or at a set time), the two webhook names, the 202 guard, refusals through SeatLayer::APIError with code, and partner seats staying out of the block.

• CHANGELOG: the "Next: 0.9.0" section. The version PR joins it with the season-2a section under ## 0.9.0.

Files changed

CHANGELOG.md, README.md, lib/seatlayer/inventory.rb, lib/seatlayer/seasons.rb, spec/client_spec.rb, spec/seasons_spec.rb (6 files, +260 −19).

Checks

• The repo's gate (bundle exec rubocop, bundle exec rspec) on Ruby 4.0 locally (CI runs 3.0, 3.2 and 3.4), re-run 10 Nov on this commit: rubocop clean (23 files); rspec 91/91.
  • The operation map spec goes 87 → 90: paths, bodies, the caller's key and the generated replay key.
  • The webhook name specs list 58.
  • A spec sends the phase 4 answers through the transport: the 202s, a job of a new kind, and the 409 codes, each a ConflictError with its code.
  • inventory_mode: on create and update.
• Mutation check (run before this amend; the code is unchanged since): 9 mutants (the 3 paths, both bodies, header replay, the guard's two halves, a missing webhook name): 9/9 killed.
• The README sample isn't run by the repo. Its syntax was checked once (ruby -c), and the calls by hand against the signatures in seasons.rb.
• Compat matrix: the same fixtures, shaped as the phase 4 API answers, through a stub transport. The script is season-phase4-ruby-compat.rb in the app session's notes; nothing is sent.

• Not done yet: a live dev smoke of the 3 calls with the dev test key. The phase 4 API isn't on dev until the stack merges; it is step 3 below.

Release steps for the owner

1. The season-2a PR (Season 2a server operations (part A) #13) merges to main, with no tag.
2. Rebase this PR onto main and retarget it to main; the gate green; merge.
3. Compat matrix again, once the phase 4 API is on dev:
   • run the compat script against RubyGems 0.8.0 and against main's lib/: both all PASS;
   • the live dev smoke of the 3 calls with the dev test key: opt in, set aside, follow the job to completed, read, release with at:, read the release job.
4. Version PR: SeatLayer::VERSION = "0.9.0" in lib/seatlayer/version.rb, and join the CHANGELOG's season-2a section ("Unreleased") and "Next: 0.9.0" under a dated ## 0.9.0. Merge to main.
5. Publish: only after the phase 4 API (paiteq/seatmap #2059 → #2086 → #2061 → #2062 → #2063 → #2066 → #2092) is live on production and the owner says yes: git tag v0.9.0 && git push origin v0.9.0. release.yml publishes to RubyGems (MFA is required, which is why releases go through the workflow), and refuses if the tag and VERSION disagree.
6. Live re-check:
   • https://rubygems.org/api/v1/versions/seatlayer/latest.json reads 0.9.0;
   • gem install seatlayer -v 0.9.0, then ruby -e 'require "seatlayer"; puts SeatLayer::VERSION';
   • run the dev smoke again from the installed gem.
7. Rollback (0.9.0 only adds): gem yank seatlayer -v 0.9.0, which needs the owner's MFA. Installs fall back to 0.8.0; a fix ships as 0.9.1. A rollback also withdraws season-2a: both ship in 0.9.0.

Failure modes

• Publishing before the phase 4 API is on production: the 3 calls would answer 404, and inventory_mode: would be ignored. Step 5 waits for production.
• A caller skipping date_leave_pending?: it would read the 202 body as the amendment. The README and the method comments point at the guard.
• Webhook names: the list is kept by hand. A name the API adds later is refused here with ArgumentError until it is added.
• Old SDKs: 0.8.0 reads the new answers through its generic error and ignores inventoryMode (compat matrix). It can't call the 3 new routes, and it refuses the two new webhook names.
• README drift: the sample isn't run. A later signature change would leave it stale.

Open risks

• No live dev smoke yet (step 3).
• The README links to the docs' "Season seats" section (/server-api/seasons/#season-seats), which goes live with paiteq/seatmap #2063. Until then the link lands on the top of the Seasons page.
• The README's season intro still counts 87 operations (it is 90 with this PR); it was left as it was.